---
title: Link | gluestack-ui | Installation, Usage, and API

description: With links, users can navigate seamlessly throughout a website. This component has a hyperlinked appearance for a user-friendly experience.

pageTitle: Link

pageDescription: With links, users can navigate seamlessly throughout a website. This component has a hyperlinked appearance for a user-friendly experience.

showHeader: true
---

import { Meta } from '@storybook/addon-docs';

<Meta title="ui/Components/Forms/Link" />

import { Link, LinkText, ArrowUpRightIcon, Icon, HStack, Text } from './Link';
import { transformedCode } from '../../../utils';
import {
  AppProvider,
  CodePreview,
  Table,
  TableContainer,
  InlineCode,
} from '@gluestack/design-system';

import Wrapper from '../../Wrapper';

This is an illustration of a **Themed Link** component with default configuration.

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
      <Link href="https://gluestack.io/">
        <LinkText>gluestack</LinkText>
      </Link>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        Link,
        LinkText,
      },
      argsType: {},
    }}
  />
</AppProvider>

<br />

## API Reference

### Import

To use this component in your project, include the following import statement in your file.

```bash
import { Link } from '@gluestack-ui/themed';
```

### Anatomy

The structure provided below can help you identify and understand a Link component's various parts.

```jsx
export default () => (
  <Link>
    <LinkText />
  </Link>
);
```

### Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

#### Link

Contains all link related layout style props and actions.
It inherits all the properties of React Native's [Pressable](https://reactnative.dev/docs/pressable) component.

<AppProvider>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Type</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>href</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>string</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`URL that should be opened on Link press.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>onPress</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>
              {'(event?: GestureResponderEvent) => any'}
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Callback that will be invoked on Link press.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isExternal</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`If true, link will be opened in new tab on web. It uses _target property to achieve this.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isHovered</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, the link displays a hover state.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isFocusVisible</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>boolean</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`To manually set focus visible state to the link.`}</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</AppProvider>

**Descendants Styling Props**
Props to style child components.

<AppProvider>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Sx Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>_text</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Prop to style LinkText Component`}</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</AppProvider>

#### LinkText

Contains all text related layout style props and actions. It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text) component.

### Accessibility

We have outlined the various features that ensure the Link component is accessible to all users, including those with disabilities. These features help ensure that your application is inclusive and meets accessibility standards. Adheres to the [WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/).

#### Keyboard

- `Tab`: Moves focus to the next focusable element.
- `Enter`: Users should be able to open a link.

#### Screen Reader

- VoiceOver: When a link receives focus, screen readers should announce a descriptive link name.

## Themed

The themed version of the component is a pre-styled version of the component, which allows you to quickly integrate the component into your project. The component's design and functionality are fully defined, allowing you to focus on the more important aspects of your project. To know more about Themed Library please visit this [link](https://gluestack.io/ui/docs/core-concepts/themed-library).

### Props

Link component is created using Pressable component from react-native. It extends all the props supported by [React Native Pressable](https://reactnative.dev/docs/pressable#props), [utility props](/ui/docs/styling/utility-and-sx-props) and the props mentioned below.

#### Link

<AppProvider>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Name</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Value</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>size</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>
              xs | sm | md | lg | xl | 2xl | 3xl | 4xl | 5xl | 6xl
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>md</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</AppProvider>

> Note: These props are exclusively applicable when utilizing the default configuration of gluestack-ui/config. If you are using a custom theme, these props may not be available.

### Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

#### Default

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
          <HStack>
            <Text
              size="lg"
            >Design inspiration from </Text>
              <Link href="https://gluestack.io/" isExternal>
                <LinkText size="lg">pinterest.com</LinkText>
              </Link>
          </HStack>
`,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: { Link, LinkText, Wrapper, ArrowUpRightIcon, Icon, HStack, Text },
      argsType: {},
    }}
  />
</AppProvider>

#### Link with icon

<AppProvider>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <HStack>
              <Text
               size="lg">Go to </Text>
              <Link href="https://gluestack.io/" isExternal>
                <HStack alignItems="center">
                <LinkText size="lg">Pinterest</LinkText>
                <Icon as={ArrowUpRightIcon} size="lg" color="$info600" mt="$0.5" $dark-color="$info300"/>
                </HStack>
              </Link>
         </HStack>
`,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: { Link, LinkText, Wrapper, ArrowUpRightIcon, Icon, HStack, Text },
      argsType: {},
    }}
  />
</AppProvider>

## Unstyled

All the components in `gluestack-ui` are unstyled by default. To customize your UI using the extendedTheme, please refer to this [link](https://gluestack.io/ui/docs/theme-configuration/customizing-theme/eject-library). The import names of components serve as keys to customize each component.

## Spec Doc

Explore the comprehensive details of the Link in this document, including its implementation details, checklist, and potential future additions. Dive into the thought process behind the component and gain insights into its development journey.

<iframe
  style={{
    borderRadius: '8px',
    border: ' 1px solid rgba(0, 0, 0, 0.1)',
    aspectRatio: 736 / 585,
  }}
  src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Fproto%2FNcXOxqKbdnGsLQNex3H76u%2F%25C2%25A0%25F0%259F%2593%259Agluestack-UI-handbook%3Fpage-id%3D5671%253A39182%26type%3Ddesign%26node-id%3D5671-40987%26viewport%3D1063%252C162%252C0.06%26t%3DMz98WWj2BmQkXQjS-1%26scaling%3Dcontain%26starting-point-node-id%3D5671%253A40987%26mode%3Ddesign"
  allowFullScreen
/>

<!--

### Customizing the Link

We have a function called `createLink` which can be used to create a custom link component. This function takes in a configuration object which contains the styled components that you want to use for the link. You can refer [gluestack.io/style](/style/docs/getting-started/styled) on how to use styled components.

#### Usage

Default styling of all these components can be found in the `components/core/link` file. For reference, you can view the [source code](https://github.com/gluestack/gluestack-ui/blob/main/packages/themed/src/components/Link) of the styled `Link` components.

```jsx
// import the styles
import { Root } from '../components/core/link/styled-components';

// import the createLink function
import { createLink } from '@gluestack-ui/link';

// Understanding the API
const Link = createLink({
  Root,
});

// Using the link component
export default () => (
  <Link href="">
    <LinkText />
  </Link>
);
```

-->

### How to use Next.js Link

By default, Link component uses an anchor tag on web and pressable on native. If you want to use Next.js Link component on web, you have to create a new styled component for link and map it to Link component. You can also change the already present styled-component for link on the path `./components/core/link/styled-components` in your project. For web specific styling, you can create a file with `.web` extension. For example, if you want to create a custom link component, you can create a file named `Link.tsx` and `Linkweb.tsx` in the same directory. The `.web` file will be used only on web and the `Link.tsx` file will be used on native.

```jsx
import Link from 'next/link';


// Using the Next Link component
const StyledLink = styled(Link, styling, componentConfig, extendedBaseConfig);

// if some styling are direct props, you can pass them as props in the styling
props: {
  w: 100,
  h: 100,
  borderRadius: '$full',
};

// you can also /style/docs/getting-started/styled to style the component


export default () => <StyledLink />;
```
